home *** CD-ROM | disk | FTP | other *** search
/ ShareWare OnLine 2 / ShareWare OnLine Volume 2 (CMS Software)(1993).iso / os2 / rxu10.zip / YDBAUTIL.INF (.txt) < prev   
OS/2 Help File  |  1993-04-08  |  57KB  |  2,182 lines
  1.  
  2. ΓòÉΓòÉΓòÉ 1. About YDBAUTIL ΓòÉΓòÉΓòÉ
  3.  
  4. YDBAUTIL is a package of diverse OS/2 Rexx External Functions. Some functions 
  5. in this package work with features of Extended Services (ES), although you do 
  6. not need to have ES installed to use the non-ES functions. Almost all the 
  7. functions in this package are in use in many of my own programs and are fairly 
  8. well de-bugged.  Please let me know of any problems you encounter in using the 
  9. functions, or of any suggestions for enhancements to existing functions, or 
  10. ideas for new ones. 
  11.  
  12.  
  13.   With the functions in the YDBAUTIL function package, you can make
  14.   use of some of OS/2's most powerful facilities, such as multi-threading,
  15.   processes, sessions, semaphores, shared memory, OS/2 queues, etc.
  16.   Some of these features are not only useful in pure Rexx applications,
  17.   but they allow you to write Rexx programs which can talk to compiled
  18.   programs on their level (i.e. reference memory by address, use
  19.   semaphores, etc.).
  20.  
  21.   Another benefit is the ability to quickly prototype real OS/2 programs
  22.   using real OS/2 APIs so that you can cheaply 'prove' techniques
  23.   before committing them to 'C' code.
  24.  
  25.   The capabilities provided to Rexx programs by this package, in
  26.   conjunction with those provided by other Rexx function packages
  27.   (database access, APPC, etc.) and the base language itself allow
  28.   you to prototype or build Rexx applications with much of the
  29.   functional sophistication (and complexity, unfortunately) of "real"
  30.   OS/2 applications.
  31.  
  32.   In addition to the many OS/2 API "passthrough" functions, there are
  33.   some Rexx-specific enhancements and additions.
  34.  
  35.  
  36.   Author:        Dave Boll
  37.                  (CompuServe = 74170,2016)
  38.                  IBMMAIL(USFMCFKF)
  39.   Release Date:  7 April, 1993
  40.   Version:       1.0
  41.  
  42.  
  43. ΓòÉΓòÉΓòÉ 2. Release Notes ΓòÉΓòÉΓòÉ
  44.  
  45. Since I haven't numbered previous versions of this package, this one 
  46. constitutes "Version 1.0". The significant difference between this version and 
  47. the previous one is related to the parameters required for the memory 
  48. management and DLL handling functions (and some others too). In general, many 
  49. of these functions used to return pointers or handles as the function result. 
  50. This made it awkward to handle return codes from the underlying APIs, and so 
  51. now the general scheme is to pass the name of a Rexx variable into which the 
  52. pointer/handle is returned.  This is all layed out in detail in the help for 
  53. each affected function. 
  54.  
  55.  
  56. ΓòÉΓòÉΓòÉ 3. How to Use It ΓòÉΓòÉΓòÉ
  57.  
  58. How to register the functions: 
  59.  
  60. In order to use the functions, you have to register them with Rexx like this:
  61.  
  62.   call rxfuncadd 'rxydbautilinit','ydbautil','rxydbautilinit'
  63.   call rxydbautilinit
  64.  
  65. The .DLL "ydbautil.dll" must be in your libpath.
  66. The .EXE "rxsrs.exe" must be in your path in order to use the function
  67. "RxStartRexxSession".
  68.  
  69.  
  70. ΓòÉΓòÉΓòÉ 4. Available External Functions ΓòÉΓòÉΓòÉ
  71.  
  72. The available functions are: 
  73.  
  74.  
  75.   Function Package utility functions
  76.   ----------------------------------
  77.   RxYdbaUtilInit        - Register all YDBAUTIL Rexx functions
  78.   RxYdbaUtilTerm        - De-Register all YDBAUTIL Rexx functions
  79.   RxYdbaUtilQuery       - Query available external function entry point names
  80.  
  81.   UPM Related
  82.   -----------
  83.   RxUpm                 - Rexx interface to UPM
  84.   RxNet                 - Rexx interface to certain NET calls
  85.                           (also some UPM-related calls)
  86.  
  87.   System-Info related
  88.   -------------------
  89.   RxProcId              - Get process' own PID and TID information
  90.   RxQuerySysInfo        - Invoke DosQuerySysInfo
  91.   RxPStat               - Obtain Process Status Information (like PSTAT)
  92.  
  93.   Rexx programming and debugging functions
  94.   ----------------------------------------
  95.   RxVlist               - List, manipulate Rexx variable pool
  96.   RxScount              - Count strings (needle) in another string (haystack)
  97.   RxPmPrintf            - Write lines to a PMPrintf Monitor
  98.   RxCallInStore         - Execute a string as a program
  99.   RxTokenize            - Tokenize ("Compile") a program string
  100.   RxPullQueue           - Pull items from any Rexx data queue
  101.   RxAddQueue            - Add items to any Rexx data queue
  102.   RxQueued              - Query number of items on any Rexx data queue
  103.   RxQExists             - Query existence of a Rexx Queue
  104.  
  105.   I/O related
  106.   -----------
  107.   RxRsoe2f              - Redirect StdOut/StdErr to a file (by file name)
  108.   RxSoSe2H              - Redirect StdOut/StdErr to a file (by file handle)
  109.   RxSi2H                - Redirect StdIn from a file (by file handle)
  110.   RxRSi2F               - Redirect StdIn from a file (by file name)
  111.   RxRead                - Read data from a file handle
  112.   RxWrite               - Write data to a file handle
  113.   RxCloseH              - Close a file handle
  114.   RxExecI               - Read data into a Rexx queue or stem from a file
  115.   RxExecO               - Write data from a Rexx queue or stem to a file
  116.  
  117.   OS/2 Pipes
  118.   ----------
  119.   RxCreateNPipe         - Create a named pipe
  120.   RxConnectNPipe        - Connect to a named pipe
  121.   RxDisConnectNPipe     - Disconnect from a named pipe
  122.   RxCreatePipe          - Create an un-named pipe
  123.   RxDestroyPipe         - Destroy a pipe
  124.  
  125.   OS/2 Queues
  126.   ----------
  127.   RxCreateQueue         - DosCreateQueue
  128.   RxOpenQueue           - DosOpenQueue
  129.   RxPeekQueue           - DosPeekQueue
  130.   RxReadQueue           - DosReadQueue
  131.   RxWriteQueue          - DosWriteQueue
  132.   RxPurgeQueue          - DosPurgeQueue
  133.   RxQueryQueue          - DosQueryQueue
  134.   RxCloseQueue          - DosCloseQueue
  135.  
  136.   NetBios information
  137.   -------------------
  138.   RxNbSessionStatus     - Obtain NETBIOS session status information
  139.  
  140.   Tasking, threads, etc.
  141.   ----------------------
  142.   RxSetPriority         - Set the priority of processes or threads
  143.             Process - Related
  144.   RxKillProcess         - Kill an OS/2 process by process-id
  145.   RxExecPgm             - Execute a program using DosExecPgm
  146.   RxStartSession        - Start a program in another session (DosStartSession)
  147.   RxStartRexxSession    - Start a Rexx program in another session
  148.             Thread - Related
  149.   RxCreateRexxThread    - Execute a Rexx program on another thread
  150.   RxCreateThread        - Call a procedure address on another thread
  151.   RxKillThread          - Kill a thread by thread-id
  152.   RxResumeThread        - Resume thread execution by thread-id
  153.   RxSuspendThread       - Suspend thread execution by thread-id
  154.   RxCallEntryPoint      - Call a (non-Rexx) routine by entry point address
  155.  
  156.   OS/2 Memory managment
  157.   ---------------------
  158.   RxStorage             - Query/Alter storage by address
  159.   RxAdd2Ptr             - Pointer Arithmetic (Add/Subtract)
  160.   RxAllocMem            - Allocate Memory
  161.   RxFreeMem             - Free Memory
  162.   RxAllocSharedMem      - Allocated Shared memory (named or un-named)
  163.   RxGetSharedMem        - Get (gettable) shared memory
  164.   RxGiveSharedMem       - Give (giveable) shared memory
  165.   RxGetNamedSharedMem   - Get named shared memory
  166.   RxSetMem              - Set memory attributes
  167.   RxQueryMem            - Query memory attributes
  168.   RxSubAllocMem         - Suballocate memory
  169.   RxSubFreeMem          - Free suballocated memory
  170.   RxSubSetMem           - Set memory for suballocation
  171.   RxSubUnsetMem         - Unset previously "SubSet" memory
  172.  
  173.   OS/2 Semaphores
  174.   ---------------
  175.              Event Semaphore
  176.   RxCreateEventSem      - Create an event semaphore
  177.   RxCloseEventSem       - Close an event semaphore
  178.   RxOpenEventSem        - Open an event semaphore
  179.   RxPostEventSem        - Post an event semaphore
  180.   RxQueryEventSem       - Query an event semaphore
  181.   RxResetEventSem       - Reset an event semaphore
  182.   RxWaitEventSem        - Wait on an event semaphore
  183.              Mutex Semaphore
  184.   RxCreateMutexSem      - Create a Mutex semaphore
  185.   RxOpenMutexSem        - Invoke DosOpenMutexSem
  186.   RxCloseMutexSem       - Invoke DosCloseMutexSem
  187.   RxQueryMutexSem       - Invoke DosQueryMutexSem
  188.   RxReleaseMutexSem     - Invoke DosReleaseMutexSem
  189.   RxRequestMutexSem     - Invoke DosRequestMutexSem
  190.              MuxWait Semaphore
  191.   RxCreateMuxWaitSem    - Invoke DosCreateMuxWaitSem
  192.   RxCloseMuxWaitSem     - Invoke DosCloseMuxWaitSem
  193.   RxOpenMuxWaitSem      - Invoke DosOpenMuxWaitSem
  194.   RxWaitMuxWaitSem      - Invoke DosWaitMuxWaitSem
  195.   RxAddMuxWaitSem       - Invoke DosAddMuxWaitSem
  196.   RxDeleteMuxWaitSem    - Invoke DosDeleteMuxWaitSem
  197.   RxQueryMuxWaitSem     - Invoke DosQueryMuxWaitSem
  198.  
  199.   DLL Handling
  200.   ------------
  201.   RxLoadModule          - Load a DLL
  202.   RxFreeModule          - Free a DLL
  203.   RxQueryModuleName     - Query the fully qualified name of a DLL (by handle)
  204.   RxQueryModuleHandle   - Query the module handle of a DLL (by name)
  205.   RxQueryProcType       - Query the addressing mode of an entry point in a DLL
  206.   RxQueryProcAddr       - Query the procedure address of an entry point in a DLL
  207.  
  208.   Rexx Macro Space Handling
  209.   -------------------------
  210.   RxAddMacro            - Add a particular Macro Space function
  211.   RxDropMacro           - Drop a particular Macro Space function
  212.   RxClearMacroSpace     - Clear the Rexx Macro Space
  213.   RxSaveMacroSpace      - Save a particular Macro Space function to a file
  214.   RxLoadMacroSpace      - Load a particular Macro Space function from a file
  215.   RxQueryMacro          - Query the position of a particular Macro Space function
  216.   RxReorderMacro        - Reorder a function's position in a Macro Space
  217.  
  218.   PM / Wp related functions
  219.   -------------------------
  220.   RxWinQueryObject      - Query object handle of a WP object
  221.   RxWinDestroyObject    - Destroy a WP object
  222.  
  223.  
  224. ΓòÉΓòÉΓòÉ 5. UPM Related Functions ΓòÉΓòÉΓòÉ
  225.  
  226. Functions which allow certain UPM activities to be performed. 
  227.  
  228.  
  229. ΓòÉΓòÉΓòÉ 5.1. RxUpm - Rexx/UPM Interface ΓòÉΓòÉΓòÉ
  230.  
  231. This function allows you to make most UPM calls from a Rexx program. 
  232.  
  233. Syntax:
  234.  
  235.   func  = 'Logon'     For Process level logon, only usable by that process */
  236.           'Logonp'
  237.         = 'Logonu'    For "User" logon, usable by all processes
  238.         = 'Logoff'    For Process level logoff, undoes a "LOGONP"
  239.           'Logoffp'
  240.         = 'Logoffu'   For "User" logoff, undoes a "LOGONU"
  241.         = 'LogonList' Gets list of current active logons
  242.   uid   = 'Userid'    Userid to be logged on/off
  243.         = 'stemname'  Name of Rexx stem variable under which results
  244.                       of "LogonList" are mapped as such:
  245.                       stem.0    - Number of logons reported on
  246.                       stem.n.1  - Userid
  247.                       stem.n.2  - Node/Domain name
  248.                       stem.n.3  - Session-Id
  249.                       stem.n.4  - Logon type (Local/Node/Domain)
  250.   pw    = 'Password'  Password to be used with 'Userid' (for logon)
  251.   type  = 'Local'     Logs you on/off UPM locally (default is LOCAL if
  252.                       no value supplied)
  253.         = 'Node'      Logs you on/off a node
  254.         = 'Domain'    Logs you on/off a LAN domain
  255.         = 'dataBase'  Logs you on/off the correct node for a database
  256.   name  = 'Name'      The name of the node/domain/database, depending on
  257.                       what "TYPE" was chosen
  258.   check = 'Admin'     Checks to see if userid has Admin authority
  259.         = 'User'      Checks to see if userid has User authority
  260.         = 'Config'    Checks to see if logon was done from Config.Sys
  261.  
  262.   upmrc = RxUpm(func, uid, pw, type, name, check)
  263.  
  264.  
  265. ΓòÉΓòÉΓòÉ 5.2. RxNet - Rexx/NET Interface ΓòÉΓòÉΓòÉ
  266.  
  267. This function allows you to make certain NetApi calls from Rexx.  This enables 
  268. you to do such things as changing passwords, adding and deleting userids, 
  269. validating a userid/pw, listing users and logons. 
  270.  
  271. Syntax:
  272.  
  273. /* General syntax */
  274.   netrc = RxNet(func, server, arg3, arg4, arg5, arg6)
  275.  
  276. where:
  277.  
  278.   func   = 'UserPwSet' /* Change a user's password */
  279.          = 'UserAdd'   /* Add a user to UPM */
  280.          = 'UserDel'   /* Delete a user from UPM */
  281.          = 'UserVal'   /* Validate a userid/password without logging on */
  282.          = 'UserEnum'  /* List users in UPM */
  283.          = 'LogonEnum' /* List active logons */
  284.          = 'FileEnum'  /* File usage on the LAN */
  285.   server = name of server, or '00'x for local
  286.   netrc  = return code from NetApi call. If netrc < 2100, then it's probably
  287.            a base OS/2 return code, otherwise, it's defined in NETCONS.H
  288.  
  289. /* Specific calls */
  290.   netrc = RxNet('UserPwSet', server, userid, oldpw, newpw)
  291.  
  292.   netrc = RxNet('UserAdd', server, userid, password, type, comment)
  293.           type = 'User', 'Guest', or 'Admin'
  294.  
  295.   netrc = RxNet('UserDel', server, userid)
  296.  
  297.   netrc = RxNet('UserVal', server, userid, password)
  298.  
  299.   netrc = RxNet('UserEnum',server, rexxstem)
  300.           rexxstem = Rexx stem name, under which results are mapped as:
  301.                      stem.0 = number of users
  302.                      stem.n.1 = userid
  303.                      stem.n.2 = privilege level (Guest, User, Admin, ?)
  304.                      stem.n.3 = password age (in seconds)
  305.                      stem.n.4 = comment
  306.  
  307.   netrc = RxNet('LogonEnum',server, rexxstem)
  308.           rexxstem = Rexx stem name, under which results are mapped as:
  309.                      stem.0 = number of users
  310.                      stem.n.1 = userid
  311.  
  312.   netrc = RxNet('FileEnum',server, basepath, username, rexxstem)
  313.           basepath = file path/name qualifier
  314.           username = username qualifier
  315.           rexxstem = Rexx stem name, under which results are mapped as:
  316.                      stem.0 = number of entries
  317.                      stem.n.1 = file-id
  318.                      stem.n.2 = permissions
  319.                      stem.n.3 = numlocks
  320.                      stem.n.4 = pathname
  321.                      stem.n.5 = username
  322.  
  323.  
  324. ΓòÉΓòÉΓòÉ 6. Rexx Programming/Debugging ΓòÉΓòÉΓòÉ
  325.  
  326. Tools for developing Rexx programs. 
  327.  
  328.  
  329. ΓòÉΓòÉΓòÉ 6.1. RxSCount - Count instances of a string ΓòÉΓòÉΓòÉ
  330.  
  331. This function returns a count of the number of instances of a string "needle" 
  332. in a string "haystack", optionally ignoring case. 
  333.  
  334. Syntax:
  335.  
  336.   numitem = rxscount(needle,haystack[,case])
  337.  
  338. where:
  339.  
  340.   needle   = string you want to count instances of
  341.   haystack = string in which you want to count instances of "needle"
  342.   case     = any character to indicate that case (upper/lower) is to
  343.              be ignored
  344.   numitem  = number of times "needle" is found in "haystack"
  345.  
  346.  
  347. ΓòÉΓòÉΓòÉ 6.2. RxPmPrintf - Write lines to a PMPrintf Monitor ΓòÉΓòÉΓòÉ
  348.  
  349. This function writes data lines to a PMPrintf "Monitor" program. 
  350.  
  351. Syntax:
  352.  
  353.   bytes = RxPmPrintf(qname, [data1 [,data2 [,data3 [...]]]] )
  354.  
  355. where:
  356.  
  357.   qname    = name of PMPrintf queue
  358.              If blank, uses default PMPrintf Queue (PRINTF32).
  359.   data1    = data to be written to PMPrintf
  360.   ...        Each argument is written as a separate line
  361.   datan
  362.  
  363.   bytes    = number of bytes written in this operation
  364.  
  365. Notes:
  366.  
  367.   The PMPrintf tool can be downloaded from the OS/2 Bulletin Board.
  368.   This Rexx function does work with PMPrintf v2.5, but does not work
  369.   with earlier versions.  You can start the PMPrintf program with
  370.   a command line argument specifying an alternate queue name for it
  371.   to use.  This queue name can be supplied as the first argument of
  372.   RxPmPrintf to direct the data to a specific running instance of
  373.   PMPrintf.
  374.  
  375.  
  376. ΓòÉΓòÉΓòÉ 6.3. RxCallInStore - Execute a string as a program ΓòÉΓòÉΓòÉ
  377.  
  378. This function allows the Rexx program developer to execute a string as though 
  379. it were a Rexx program.  This allows you to build the equivalent of a Rexx 
  380. program's text in a variable, and then execute it from the string.  Actually, 
  381. the Rexx program text can come from anywhere -- a file, over a communications 
  382. link, from a database. For repeated execution of a program, use "RxTokenize" to 
  383. "compile" the program, then call "RxCallInStore" with "&" to re-use the 
  384. tokenized program. 
  385.  
  386. Syntax:
  387.  
  388.   result = RxCallInStore strtext, arg1, arg2, ..., arg19
  389.  
  390. where:
  391.  
  392.   strtext  = text of a Rexx program, complete with crlf and eof markers
  393.                   or
  394.              a '$' immediately preceding a source program string
  395.                   or
  396.              a '&' immediately preceding a tokenized program string
  397.   arg1     = arguments to the called program
  398.   ...
  399.   arg19
  400.  
  401. Note:
  402.  
  403.   Example of executing a program string:
  404.  
  405.     crlf = '0d0a'x
  406.     str = '/* Rexx */'crlf
  407.     str = str 'Do i=1 To Arg()'crlf
  408.     str = str '  Say "Arg#"i "= {"arg(i)"}"'crlf
  409.     str = str 'End'crlf
  410.     str = str||'1a'x       /* EOF marker */
  411.     call rxcallinstore str, date(), time()
  412.                ( or )
  413.     call rxcallinstore '$'str, date(), time()
  414.                ( or )
  415.     tstr = rxtokenize(str)
  416.     call rxcallinstore '&'tstr, date(), time()
  417.  
  418.  
  419. ΓòÉΓòÉΓòÉ 6.4. RxTokenize - Tokenize a program source string ΓòÉΓòÉΓòÉ
  420.  
  421. This function in effect "compiles" a program source string for re-use with 
  422. subsequent "RxCallInstore" or "RxCreateRexxThread" calls. This provides better 
  423. performance when a program string is repeatedly called. 
  424.  
  425. Syntax:
  426.  
  427.   tokenstr = RxTokenize(progstr)
  428.  
  429. where:
  430.  
  431.   progstr  = actual Rexx program source string
  432.   tokenstr = tokenized ("compiled") result of "progstr"
  433.  
  434. Note:
  435.  
  436.   This function, in conjunction with the "RxCallInstore" and/or
  437.   "RxCreateRexxThread" functions, can be used to achieve the same
  438.   effect as the Rexx Macrospace, except that this technique is local
  439.   to the program using it (whereas the Macrospace is system global).
  440.  
  441.  
  442. ΓòÉΓòÉΓòÉ 6.5. RxVlist - Display/Process Rexx Variables ΓòÉΓòÉΓòÉ
  443.  
  444. This function allows the Rexx program developer to view portions of the Rexx 
  445. variable pool.  It also allows you to effectively "pass" variable pools (or 
  446. subsets thereof) between execs across Rexx queues. 
  447.  
  448. Syntax:
  449.  
  450.   numvar = RxVlist( [vnamepat] [,func] [,qname] )
  451.  
  452. where:
  453.  
  454.   func     = 'V'  /* Puts variable name/value pairs on a queue */
  455.            = 'N'  /* Puts variable names on a queue */
  456.            = 'G'  /* Gets variable name/value pairs off a queue */
  457.                   /* and incorporates them into the current variable pool */
  458.            = 'D'  /* display variables and their values (default) */
  459.   vnamepat = variable name prefix (every variable whose name begins with this
  460.              value is processed according to the specified function)
  461.              (default is all variables)
  462.   qname    = name of a Rexx queue to use (default is the current queue)
  463.  
  464.  
  465. ΓòÉΓòÉΓòÉ 6.6. RxPullQueue - Pull items off any Rexx queue ΓòÉΓòÉΓòÉ
  466.  
  467. This function does what the Rexx "Pull" instruction and "LineIn" functions do, 
  468. except this function allows you to specify the queue name as part of the call, 
  469. regardless of what the current queue may be. 
  470.  
  471. Syntax:
  472.  
  473.   data = RxPullQueue( [qname] [,type] [,rexxvar] )
  474.  
  475. where:
  476.  
  477.   qname   = name of Rexx queue to pull from (default is current queue)
  478.   type    = 'Wait' or 'Nowait' (default is 'Wait')
  479.   rexxvar = name of a Rexx variable into which is put the queue-insertion-
  480.             timestamp for the retreived element
  481.   data    = data obtained from queue
  482.  
  483.  
  484. ΓòÉΓòÉΓòÉ 6.7. RxAddQueue - Add items to any Rexx queue ΓòÉΓòÉΓòÉ
  485.  
  486. This function does what the Rexx "Queue" and "Push" instructions, and the 
  487. "LineOut" function do, except this function allows you to specify the queue 
  488. name as part of the call, regardless of what the current queue may be. 
  489.  
  490. Syntax:
  491.  
  492.   qrc = RxAddQueue( data [,qname] [,type] )
  493.  
  494. where:
  495.  
  496.   data  = data to be placed on queue
  497.   qname = name of Rexx queue to add to (default is current queue)
  498.   type  = 'Queue' or 'Push' (default is 'Queue')
  499.  
  500.  
  501. ΓòÉΓòÉΓòÉ 6.8. RxQueued - Query number of items on any Rexx queue ΓòÉΓòÉΓòÉ
  502.  
  503. This function does what the Rexx "Queued" function does, except this function 
  504. allows you to specify the queue name as part of the call, regardless of what 
  505. the current queue may be. 
  506.  
  507. Syntax:
  508.  
  509.   numq = RxQueued( [qname] )
  510.  
  511. where:
  512.  
  513.   qname = name of Rexx queue to report on (default is current queue)
  514.  
  515.  
  516. ΓòÉΓòÉΓòÉ 6.9. RxQExists - Query existence of a Rexx Queue ΓòÉΓòÉΓòÉ
  517.  
  518. This function returns "1" or "0", indicating the existence of the Rexx Queue 
  519. whose name you supply as an argument. 
  520.  
  521. Syntax:
  522.  
  523.   bool = RxQExists( [qname] )
  524.  
  525. where:
  526.  
  527.   qname = name of Rexx queue to check for existence of
  528.   bool  = truth value of queue's existence
  529.  
  530.  
  531. ΓòÉΓòÉΓòÉ 7. Memory Management/Access ΓòÉΓòÉΓòÉ
  532.  
  533. These functions allow Rexx programs to create, access, and manage OS/2 memory 
  534. objects by address.  This includes objects such as shared memory (named and 
  535. un-named). 
  536.  
  537.  
  538. ΓòÉΓòÉΓòÉ 7.1. RxStorage - Access/Alter memory by address ΓòÉΓòÉΓòÉ
  539.  
  540. This function allows a Rexx program to access and/or alter storage by address. 
  541. This could be used to process data passed to it by a program.  This could also 
  542. be used to "Pass By Reference" among Rexx programs when using the RxAllocMem 
  543. and RxFreeMem functions. 
  544.  
  545. Syntax:
  546.  
  547.   outdata = RxStorage( pointer [, length] [, indata] )
  548.  
  549. where
  550.  
  551.   pointer  = 32-bit pointer (address)
  552.   length   = Length of storage to be queried (defaults to 1)
  553.   indata   = Data to place at address "pointer" for the length of the data
  554.              (regardless of "length" value)
  555.   outdata  = Data at address "pointer" for length "length" (truncated if
  556.              "length" takes you beyond allowed storage)
  557.  
  558. Note:
  559.  
  560.   A request to query memory out-of-bounds returns a string up to the bound-
  561.   ary.  A request to set memory out-of-bounds, sets memory up to the bound-
  562.   ary.  All memory is allocated in 4k chunks.  Therefore, some query or set
  563.   operations will access memory up to the next 4k boundary.
  564.  
  565.  
  566. ΓòÉΓòÉΓòÉ 7.2. RxAdd2Ptr - Pointer Arithmetic (Add/Subtract) ΓòÉΓòÉΓòÉ
  567.  
  568. This function allows a Rexx program to add or subtract from an OS/2 32-bit 
  569. linear address. 
  570.  
  571. Syntax:
  572.  
  573.   newptr = RxAdd2Ptr( pointer , [number] )
  574.  
  575. where:
  576.  
  577.   pointer  = 32-bit pointer (address)
  578.   number   = amount by which "pointer" is to be incremented/decremented
  579.              in bytes.  Default is zero.
  580.   newptr   = result of addition/subtraction
  581.  
  582.  
  583. ΓòÉΓòÉΓòÉ 7.3. RxAllocMem - Allocate memory (using DosAllocMem) ΓòÉΓòÉΓòÉ
  584.  
  585. This function allows a Rexx program to allocate memory.  This memory can then 
  586. be accessed using RxStorage. 
  587.  
  588. Syntax:
  589.  
  590.   allocrc = RxAllocMem(rexxvar, length, flags)
  591.  
  592. where
  593.  
  594.   rexxvar = name of a rexx variable in which pointer is returned
  595.   length  = a decimal integer indicating amount of storage (in bytes) to
  596.             allocate
  597.   flags   = any combination of:
  598.             C - Pag_Commit
  599.             T - Obj_Tile
  600.             X - Pag_Execute
  601.             R - Pag_Read
  602.             W - Pag_Write
  603.             G - Pag_Guard
  604.   allocrc = return code from DosAllocMem()
  605.  
  606. for example:
  607.             /* Following would get 4k committed read/write */
  608.   allocrc = RxAllocMem('pointer', 4096, 'crw')
  609.  
  610. Note:
  611.  
  612.   All memory is allocated in 4k chunks.  Therefore, even if you allocate 200
  613.   bytes, you will get access to 4096 bytes.
  614.  
  615.  
  616. ΓòÉΓòÉΓòÉ 7.4. RxFreeMem - Free memory allocated by RxAllocMem ΓòÉΓòÉΓòÉ
  617.  
  618. This function allows a Rexx program to free memory allocated by RxAllocMem. 
  619.  
  620. Syntax:
  621.  
  622.   freerc = RxFreeMem(pointer)
  623.  
  624. where
  625.  
  626.   pointer - A valid 32 bit pointer.
  627.  
  628. Note:
  629.  
  630.   Returned value is return code from DosFreeMem
  631.  
  632.  
  633. ΓòÉΓòÉΓòÉ 7.5. RxAllocSharedMem - Allocate shared memory ΓòÉΓòÉΓòÉ
  634.  
  635. This function allocates shared (named or un-named) memory.  Other processes can 
  636. access this memory with either RxGetSharedMem (un-named), or 
  637. RxGetNamedSharedMem (named), or if it is "Given", followed by calls to 
  638. RxStorage. 
  639.  
  640. Syntax:
  641.  
  642.   allocrc = RxAllocSharedMem(rexxvar, length, flags [,memname] )
  643.  
  644. where
  645.  
  646.   rexxvar = name of a rexx variable in which pointer is returned
  647.   length  = a decimal integer indicating amount of storage (in bytes) to
  648.             allocate
  649.   flags   = any combination of:
  650.             C - Pag_Commit
  651.             T - Obj_Tile
  652.             I - Obj_Giveable
  653.             E - Obj_Gettable (sic)
  654.             X - Pag_Execute
  655.             R - Pag_Read
  656.             W - Pag_Write
  657.             G - Pag_Guard
  658.   memname = name of shared memory object, if this is to be named shared
  659.             memory
  660.   allocrc = return code from DosAllocSharedMem()
  661.  
  662. for example:
  663.  
  664.   /* To allocate an un-named, gettable object */
  665.   allocrc = RxAllocSharedMem('pointer', 4096, 'cerw')
  666.  
  667.   /* To allocate a named object */
  668.   allocrc = RxAllocSharedMem('pointer', 4096, 'crw','\SHAREMEM\TEST.MEM')
  669.  
  670. Note:
  671.  
  672.   All memory is allocated in 4k chunks.  Therefore, even if you allocate 200
  673.   bytes, you will get access to 4096 bytes.
  674.  
  675.  
  676. ΓòÉΓòÉΓòÉ 7.6. RxGiveSharedMem - Give access to shared memory ΓòÉΓòÉΓòÉ
  677.  
  678. This function gives access to shared, un-named memory to a process-id 
  679.  
  680. Syntax:
  681.  
  682.   giverc = RxGiveSharedMem(pointer, pid [,flags])
  683.  
  684. where
  685.  
  686.   pointer = valid 32-bit pointer
  687.   pid     = valid process-id (as a decimal integer)
  688.   flags   = any combination of:
  689.             X - Pag_Execute
  690.             R - Pag_Read
  691.             W - Pag_Write
  692.             G - Pag_Guard
  693.  
  694. for example:
  695.  
  696.   /* To give shared memory */
  697.   giverc = RxGiveSharedMem(pointer, 23, 'rw')
  698.  
  699. Note:
  700.  
  701.   A valid pointer must be supplied.  This is obtained from the process which
  702.   allocated the shared un-named memory via RxAllocSharedMem.  The process-id
  703.   supplied must be valid (i.e. must currently exist).
  704.  
  705.  
  706. ΓòÉΓòÉΓòÉ 7.7. RxGetSharedMem - Get access to shared memory ΓòÉΓòÉΓòÉ
  707.  
  708. This function gets access to shared, un-named, gettable memory. 
  709.  
  710. Syntax:
  711.  
  712.   getrc = RxGetSharedMem(pointer, flags)
  713.  
  714. where
  715.  
  716.   pointer = valid 32-bit pointer
  717.   flags   = any combination of:
  718.             X - Pag_Execute
  719.             R - Pag_Read
  720.             W - Pag_Write
  721.             G - Pag_Guard
  722.  
  723. for example:
  724.  
  725.   /* To get shared memory */
  726.   getrc = RxGetSharedMem(pointer, 'rw')
  727.  
  728. Note:
  729.  
  730.   A valid pointer must be supplied.  This is obtained from the process which
  731.   allocated the shared un-named memory via RxAllocSharedMem.
  732.  
  733.  
  734. ΓòÉΓòÉΓòÉ 7.8. RxGetNamedSharedMem - Get access to named shared memory ΓòÉΓòÉΓòÉ
  735.  
  736. This function gets access to shared, named memory. 
  737.  
  738. Syntax:
  739.  
  740.   getrc = RxGetNamedSharedMem(rexxvar, memname, flags)
  741.  
  742. where
  743.  
  744.   rexxvar = name of a rexx variable in which pointer is returned
  745.   memname = valid name of a shared memory object
  746.   flags   = any combination of:
  747.             X - Pag_Execute
  748.             R - Pag_Read
  749.             W - Pag_Write
  750.             G - Pag_Guard
  751.   getrc   = return code from DosGetNamedSharedMem()
  752.  
  753. for example:
  754.  
  755.   /* To get named shared memory */
  756.   getrc = RxGetNamedSharedMem('pointer', '\SHAREMEM\TEST.MEM', 'rw')
  757.  
  758.  
  759. ΓòÉΓòÉΓòÉ 7.9. RxSetMem - Set memory attributes ΓòÉΓòÉΓòÉ
  760.  
  761. This function sets memory attributes using DosSetMem 
  762.  
  763. Syntax:
  764.  
  765.   setrc = RxSetMem(pointer [,memsize [,flags]])
  766.  
  767. where
  768.  
  769.   pointer = valid 32-bit pointer
  770.   memsize = size of memory block to set
  771.   flags   = any combination of:
  772.             C - Pag_Commit
  773.             D - Pag_Decommit
  774.             F - Pag_Default
  775.             X - Pag_Execute
  776.             R - Pag_Read
  777.             W - Pag_Write
  778.             G - Pag_Guard
  779.  
  780. for example:
  781.  
  782.   /* To set memory attributes */
  783.   setrc = RxSetMem(pointer, 4096, 'crw')
  784.  
  785. Note:
  786.  
  787.   Returned value is return code from DosSetMem.
  788.  
  789.  
  790. ΓòÉΓòÉΓòÉ 7.10. RxQueryMem - Query memory attributes ΓòÉΓòÉΓòÉ
  791.  
  792. This function queries memory attributes using DosQueryMem 
  793.  
  794. Syntax:
  795.  
  796.   qinfo = RxQueryMem(pointer [,memsize])
  797.  
  798. where
  799.  
  800.   pointer = valid 32-bit pointer
  801.   memsize = size of memory block to query
  802.   qinfo   = either one or three blank-delimited tokens:
  803.             1) return code from DosQueryMem
  804.                If #1 is zero:
  805.                  2) actual memory size
  806.                  3) memory attribute flags, which can be any combination of:
  807.                     C - Pag_Commit
  808.                     F - Pag_Free
  809.                     S - Pag_Shared
  810.                     B - Pag_Base
  811.                     X - Pag_Execute
  812.                     R - Pag_Read
  813.                     W - Pag_Write
  814.                     G - Pag_Guard
  815.  
  816. for example:
  817.  
  818.   /* To query memory attributes */
  819.   qinfo = RxQueryMem(pointer, 4096)
  820.   /* "Say qinfo" might say -> "0 4096 CSRW" for instance */
  821.  
  822. Note:
  823.  
  824.   If first token is not zero, no other information was returned.
  825.  
  826.  
  827. ΓòÉΓòÉΓòÉ 7.11. RxSubSetMem - Set memory for suballocation ΓòÉΓòÉΓòÉ
  828.  
  829. This function sets memory for suballocation using DosSubSetMem 
  830.  
  831. Syntax:
  832.  
  833.   subsetrc = RxSubSetMem(pointer [,memsize [,flags]])
  834.  
  835. where
  836.  
  837.   pointer = valid 32-bit pointer to pool
  838.   memsize = size of memory block to subset
  839.   flags   = any combination of:
  840.             I - DosSub_Init
  841.             G - DosSub_Grow
  842.             S - DosSub_Sparse
  843.             R - DosSub_Serialize
  844.  
  845. for example:
  846.  
  847.   /* To subset some memory */
  848.   subsetrc = RxSubSetMem(pointer, 4096, 'i')
  849.  
  850. Note:
  851.  
  852.   Returned value is return code from DosSubSetMem.
  853.  
  854.  
  855. ΓòÉΓòÉΓòÉ 7.12. RxSubUnSetMem - UnSet memory from suballocation ΓòÉΓòÉΓòÉ
  856.  
  857. This function unsets memory from suballocation using DosSubUnSetMem 
  858.  
  859. Syntax:
  860.  
  861.   subunsetrc = RxSubUnSetMem(pointer)
  862.  
  863. where
  864.  
  865.   pointer = valid 32-bit pointer to pool
  866.  
  867. for example:
  868.  
  869.   /* To subunset some memory */
  870.   subunsetrc = RxSubUnSetMem(pointer)
  871.  
  872. Note:
  873.  
  874.   Returned value is return code from DosSubUnSetMem.
  875.  
  876.  
  877. ΓòÉΓòÉΓòÉ 7.13. RxSubAllocMem - Suballocate memory ΓòÉΓòÉΓòÉ
  878.  
  879. This function suballocates memory. 
  880.  
  881. Syntax:
  882.  
  883.   subarc = RxSubAllocMem(rexxvar, pointer [,memsize])
  884.  
  885. where
  886.  
  887.   rexxvar = name of a rexx variable in which block offset is returned
  888.   pointer = valid 32-bit pointer to pool
  889.   memsize = size of block to suballocate
  890.   subarc  = return code from DosSubAllocMem()
  891.  
  892. for example:
  893.  
  894.   /* To suballocate some memory */
  895.   subarc = RxSubAllocMem('block_offset', pointer, 4096)
  896.  
  897.  
  898. ΓòÉΓòÉΓòÉ 7.14. RxSubFreeMem - Free suballocated memory ΓòÉΓòÉΓòÉ
  899.  
  900. This function frees suballocated memory. 
  901.  
  902. Syntax:
  903.  
  904.   freerc = RxSubFreeMem(pointer, boffset [,memsize])
  905.  
  906. where
  907.  
  908.   pointer = valid 32-bit pointer to pool
  909.   boffset = block offset pointer
  910.   memsize = size of block to free
  911.  
  912. for example:
  913.  
  914.   /* To free suballocated memory */
  915.   freerc = RxSubFreeMem(pointer, boffset, 4096)
  916.  
  917. Note:
  918.  
  919.   Returned value is return code from DosSubFreeMem.
  920.  
  921.  
  922. ΓòÉΓòÉΓòÉ 8. Sempahore handling ΓòÉΓòÉΓòÉ
  923.  
  924. These functions allow Rexx programs to make use of OS/2 semaphores for 
  925. synchronization/serialization purposes. 
  926.  
  927.  
  928. ΓòÉΓòÉΓòÉ 8.1. RxCreateEventSem - Create an event semaphore ΓòÉΓòÉΓòÉ
  929.  
  930. This function creates a (named or un-named) event semaphore. 
  931.  
  932. Syntax:
  933.  
  934.   semrc = RxCreateEventSem(rexxvar [,type] [,name] [,state] )
  935.  
  936. where
  937.  
  938.   rexxvar = name of a rexx variable in which sem handle is returned
  939.   type    = 'Shared' or 'Private' (default is Private)
  940.   name    = semaphore name (default is un-named)
  941.   state   = 'Reset' or 'Posted' (default is Reset)
  942.   semrc   = return code from DosCreateEventSem()
  943.  
  944.  
  945. ΓòÉΓòÉΓòÉ 8.2. RxOpenEventSem - Open an event semaphore ΓòÉΓòÉΓòÉ
  946.  
  947. This function opens an event semaphore for use by a process that did not create 
  948. the semaphore. 
  949.  
  950. Syntax:
  951.  
  952.   semrc = RxOpenEventSem(rexxvar, semid)
  953.  
  954. where
  955.  
  956.   rexxvar = name of a rexx variable in which sem handle is returned
  957.   semid   = either a semaphore handle, or a semaphore name
  958.   semrc   = return code from DosOpenEventSem()
  959.  
  960. Note:
  961.  
  962.   A zero length string is returned if DosOpenEventSem fails.
  963.  
  964.  
  965. ΓòÉΓòÉΓòÉ 8.3. RxPostEventSem - Post an event semaphore ΓòÉΓòÉΓòÉ
  966.  
  967. This function posts an event semaphore. 
  968.  
  969. Syntax:
  970.  
  971.   postrc = RxPostEventSem(hev)
  972.  
  973. where
  974.  
  975.   hev    = semaphore handle
  976.   postrc = return code from DosPostEventSem
  977.  
  978.  
  979. ΓòÉΓòÉΓòÉ 8.4. RxQueryEventSem - Query an event semaphore ΓòÉΓòÉΓòÉ
  980.  
  981. This function returns the post count for an event semaphore. 
  982.  
  983. Syntax:
  984.  
  985.   info = RxQueryEventSem(hev)
  986.  
  987. where
  988.  
  989.   hev    = semaphore handle
  990.   info   = return code from DosQueryEventSem, followed by number of posts
  991. Note:
  992.  
  993.   Word 1 of info is the return code from DosQueryEventSem
  994.   Word 2 of info is the actual number of posts to the semaphore
  995.  
  996.  
  997. ΓòÉΓòÉΓòÉ 8.5. RxResetEventSem - Reset an event semaphore ΓòÉΓòÉΓòÉ
  998.  
  999. This function resets an event semaphore, returning the number of postings for 
  1000. that semaphore. 
  1001.  
  1002. Syntax:
  1003.  
  1004.   info = RxResetEventSem(hev)
  1005.  
  1006. where
  1007.  
  1008.   hev    = semaphore handle
  1009.   info   = return code from DosResetEventSem, followed by number of posts
  1010.  
  1011. Note:
  1012.  
  1013.   Word 1 of info is the return code from DosResetEventSem
  1014.   Word 2 of info is the actual number of posts to the semaphore before
  1015.                     the Reset.
  1016.  
  1017.  
  1018. ΓòÉΓòÉΓòÉ 8.6. RxWaitEventSem - Wait on an event semaphore ΓòÉΓòÉΓòÉ
  1019.  
  1020. This function waits on the posting of an event semaphore. 
  1021.  
  1022. Syntax:
  1023.  
  1024.   semhandle /* A valid semaphore handle */
  1025.   time = 1000   /* in milliseconds */
  1026.  
  1027.   waitrc = RxWaitEventSem(hev [,time])
  1028.  
  1029. where
  1030.  
  1031.   hev    = semaphore handle
  1032.   time   = number of miliseconds to wait before returning, or the word
  1033.            'Indefinite'.  Default is 'Indefinite'.
  1034.   waitrc = return code from DosWaitEventSem
  1035.  
  1036.  
  1037. ΓòÉΓòÉΓòÉ 8.7. RxCloseEventSem - Close an event semaphore ΓòÉΓòÉΓòÉ
  1038.  
  1039. This function closes an event semaphore 
  1040.  
  1041. Syntax:
  1042.  
  1043.   closerc = RxCloseEventSem(hev)
  1044.  
  1045. where
  1046.  
  1047.   hev     = semaphore handle
  1048.   closerc = return code from DosCloseEventSem
  1049.  
  1050.  
  1051. ΓòÉΓòÉΓòÉ 8.8. RxCreateMutexSem - Create a Mutex Semaphore ΓòÉΓòÉΓòÉ
  1052.  
  1053. This function creates a mutex semaphore 
  1054.  
  1055. Syntax:
  1056.  
  1057.   semrc = RxCreateMutexSem(rexxvar [,type] [,name] [,state] )
  1058.  
  1059. where
  1060.  
  1061.   rexxvar = name of a rexx variable in which sem handle is returned
  1062.   type    = 'Shared' or 'Private' (default is 'Private')
  1063.   name    = semaphore name (default is un-named)
  1064.   state   = 'Owned' or 'Unowned' (default is un-owned)
  1065.   semrc   = return code from DosCreateMutexSem()
  1066.  
  1067.  
  1068. ΓòÉΓòÉΓòÉ 8.9. RxOpenMutexSem - Open a Mutex Semaphore ΓòÉΓòÉΓòÉ
  1069.  
  1070. This function opens a mutex semaphore 
  1071.  
  1072. Syntax:
  1073.  
  1074.   semrc = RxOpenMutexSem(rexxvar, semid )
  1075.  
  1076. where
  1077.  
  1078.   rexxvar = name of a rexx variable in which sem handle is returned
  1079.   semid   = either a semaphore name, or an existing mutex semaphore handle
  1080.   semrc   = return code from DosOpenMutexSem()
  1081.  
  1082.  
  1083. ΓòÉΓòÉΓòÉ 8.10. RxCloseMutexSem - Close a Mutex Semaphore ΓòÉΓòÉΓòÉ
  1084.  
  1085. This function closes a mutex semaphore 
  1086.  
  1087. Syntax:
  1088.  
  1089.   mtxrc = RxCloseMutexSem( hmtx )
  1090.  
  1091. where
  1092.  
  1093.   hmtx  = existing mutex semaphore handle
  1094.   mtxrc = return code from DosCloseMutexSem
  1095.  
  1096.  
  1097. ΓòÉΓòÉΓòÉ 8.11. RxQueryMutexSem - Query Mutex Semaphore ΓòÉΓòÉΓòÉ
  1098.  
  1099. This function queries a mutex semaphore's attributes 
  1100.  
  1101. Syntax:
  1102.  
  1103.   mtxinfo = RxQueryMutexSem( hmtx )
  1104.  
  1105. where
  1106.  
  1107.   hmtx    = existing mutex semaphore handle
  1108.   mtxinfo = four blank delimited tokens:
  1109.             1) return code from DosQueryMutexSem
  1110.             2) Process-Id of semaphore's current owner
  1111.             3) Thread-Id of semaphore's current owner
  1112.             4) A count of the number of calls to DosRequestMutexSem,
  1113.                minus the number of calls to DosReleaseMutexSem, that have
  1114.                been made for the semaphore by the owning thread.
  1115.                If the semaphore is unowned, this value will be zero.
  1116.                If the owning thread has ended, the value will be the
  1117.                request count for the ended owner.
  1118.  
  1119.  
  1120. ΓòÉΓòÉΓòÉ 8.12. RxReleaseMutexSem - Release Mutex Semaphore ΓòÉΓòÉΓòÉ
  1121.  
  1122. This function releases a mutex semaphore 
  1123.  
  1124. Syntax:
  1125.  
  1126.   mtxrc = RxReleaseMutexSem( hmtx )
  1127.  
  1128. where
  1129.  
  1130.   hmtx  = existing mutex semaphore handle
  1131.   mtxrc = return code from DosReleaseMutexSem
  1132.  
  1133.  
  1134. ΓòÉΓòÉΓòÉ 8.13. RxRequestMutexSem - Request Mutex Semaphore ΓòÉΓòÉΓòÉ
  1135.  
  1136. This function requests a mutex semaphore 
  1137.  
  1138. Syntax:
  1139.  
  1140.   mtxrc = RxRequestMutexSem( hmtx [, timeout] )
  1141.  
  1142. where
  1143.  
  1144.   hmtx    = existing mutex semaphore handle
  1145.   timeout = either a decimal integer (miliseconds to block), or the word
  1146.             'Indefinite'
  1147.   mtxrc   = return code from DosRequestMutexSem
  1148.  
  1149.  
  1150. ΓòÉΓòÉΓòÉ 8.14. RxCreateMuxWaitSem - Create a MuxWait Semaphore ΓòÉΓòÉΓòÉ
  1151.  
  1152. This function creates a muxwait semaphore 
  1153.  
  1154. Syntax:
  1155.  
  1156.   semrc = RxCreateMuxWaitSem(rexxvar, stemname [,type] [,anyall]
  1157.                              [,name] )
  1158.  
  1159. where
  1160.  
  1161.   rexxvar  = name of a rexx variable in which sem handle is returned
  1162.   stemname = a Rexx stem name (ending in a period '.'), under which are
  1163.              supplied the semaphore handles which constitute this muxwait
  1164.              semaphore.  The expected structure of the stem is:
  1165.              1) stem.0   = a decimal integer indicating how many semaphores
  1166.                            are supplied
  1167.              2) stem.n.1 = handle of Nth semaphore
  1168.              3) stem.n.2 = decimal integer used as an Id for Nth semaphore
  1169.   type     = 'Shared' or 'Private' (default is 'Private')
  1170.   anyall   = 'Any' or 'All' (default is 'All')
  1171.   name     = semaphore name (default is un-named)
  1172.   semrc    = return code from DosCreateMuxWaitSem()
  1173.  
  1174.  
  1175. ΓòÉΓòÉΓòÉ 8.15. RxOpenMuxWaitSem - Open a MuxWait Semaphore ΓòÉΓòÉΓòÉ
  1176.  
  1177. This function opens a muxwait semaphore 
  1178.  
  1179. Syntax:
  1180.  
  1181.   semrc = RxOpenMuxWaitSem(rexxvar, semid )
  1182.  
  1183. where
  1184.  
  1185.   rexxvar = name of a rexx variable in which sem handle is returned
  1186.   semid   = either a semaphore name, or an existing muxwait
  1187.             semaphore handle
  1188.   semrc   = return code from DosOpenMuxWaitSem()
  1189.  
  1190.  
  1191. ΓòÉΓòÉΓòÉ 8.16. RxCloseMuxWaitSem - Close a MuxWait Semaphore ΓòÉΓòÉΓòÉ
  1192.  
  1193. This function closes a muxwait semaphore 
  1194.  
  1195. Syntax:
  1196.  
  1197.   muxrc = RxCloseMuxWaitSem( hmux )
  1198.  
  1199. where
  1200.  
  1201.   hmux  = existing muxwait semaphore handle
  1202.   muxrc = return code from DosCloseMuxWaitSem
  1203.  
  1204.  
  1205. ΓòÉΓòÉΓòÉ 8.17. RxDeleteMuxWaitSem - Delete from a MuxWait Semaphore ΓòÉΓòÉΓòÉ
  1206.  
  1207. This function deletes a semaphore from a muxwait semaphore list 
  1208.  
  1209. Syntax:
  1210.  
  1211.   muxrc = RxDeleteMuxWaitSem( hmux, hsem )
  1212.  
  1213. where
  1214.  
  1215.   hmux  = existing muxwait semaphore handle
  1216.   hsem  = handle of a semaphore in the muxwait semaphore list
  1217.   muxrc = return code from DosDeleteMuxWaitSem
  1218.  
  1219.  
  1220. ΓòÉΓòÉΓòÉ 8.18. RxAddMuxWaitSem - Add to a MuxWait Semaphore ΓòÉΓòÉΓòÉ
  1221.  
  1222. This function adds a semaphore to a muxwait semaphore list 
  1223.  
  1224. Syntax:
  1225.  
  1226.   muxrc = RxAddMuxWaitSem( hmux, hsem, semid )
  1227.  
  1228. where
  1229.  
  1230.   hmux  = existing muxwait semaphore handle
  1231.   hsem  = handle of a semaphore to add to the muxwait semaphore list
  1232.   semid = decimal integer used as an Id for this semaphore
  1233.   muxrc = return code from DosAddMuxWaitSem
  1234.  
  1235.  
  1236. ΓòÉΓòÉΓòÉ 8.19. RxQueryMuxWaitSem - Query a MuxWait Semaphore ΓòÉΓòÉΓòÉ
  1237.  
  1238. This function queries information about a muxwait semaphore 
  1239.  
  1240. Syntax:
  1241.  
  1242.   muxinfo = RxQueryMuxWaitSem( hmux, stemname )
  1243.  
  1244. where
  1245.  
  1246.   hmux     = existing muxwait semaphore handle
  1247.   stemname = a Rexx stem name (ending in a period '.'), under which is
  1248.              returned information about the muxwait semaphore.  The structure
  1249.              of the returned information is:
  1250.              1) stem.0   = a decimal integer indicating how many semaphores
  1251.                            are listed in this muxwait semaphore
  1252.              2) stem.n.1 = handle of Nth semaphore
  1253.              3) stem.n.2 = decimal integer Id of Nth semaphore
  1254.   muxinfo  = Two blank delimited tokens:
  1255.              1) return code from DosQueryMuxWaitSem
  1256.              2) a string of letters indicating this muxwait semaphore's
  1257.                 properties:
  1258.                 'S' if it's shared
  1259.                 'Y' if it's a wait ANY
  1260.                 'L' if it's a wait ALL
  1261.  
  1262.  
  1263. ΓòÉΓòÉΓòÉ 8.20. RxWaitMuxWaitSem - Wait on a MuxWait Semaphore ΓòÉΓòÉΓòÉ
  1264.  
  1265. This function waits on a muxwait semaphore 
  1266.  
  1267. Syntax:
  1268.  
  1269.   muxinfo = RxWaitMuxWaitSem( hmux [,timeout] )
  1270.  
  1271. where
  1272.  
  1273.   hmux     = existing muxwait semaphore handle
  1274.   timeout  = either a decimal integer (miliseconds to block), or the word
  1275.             'Indefinite'
  1276.   muxinfo  = Two blank delimited tokens:
  1277.              1) return code from DosQueryMuxWaitSem
  1278.              2) semaphore-id of releaser of muxwait sem (for more info,
  1279.                 see details of DosWaitMuxWaitSem)
  1280.  
  1281.  
  1282. ΓòÉΓòÉΓòÉ 9. Rexx Macro Space Functions ΓòÉΓòÉΓòÉ
  1283.  
  1284. These functions allow Rexx programs to query and alter the Rexx MacroSpace. 
  1285.  
  1286.  
  1287. ΓòÉΓòÉΓòÉ 9.1. RxAddMacro - Add Entry to MacroSpace ΓòÉΓòÉΓòÉ
  1288.  
  1289. This function adds a Rexx program to the macrospace. 
  1290.  
  1291. Syntax:
  1292.  
  1293.   addrc = RxAddMacro(funcname, sourcefile [,order])
  1294.  
  1295. where
  1296.  
  1297.   funcname   = name for function in macrospace
  1298.   sourcefile = name of source file where Rexx source code exists
  1299.   order      = order in macrospace (Before or After)
  1300.  
  1301. Note:
  1302.  
  1303.   Returned value is return code from RexxAddMacro.
  1304.  
  1305.  
  1306. ΓòÉΓòÉΓòÉ 9.2. RxDropMacro - Drop Entry from MacroSpace ΓòÉΓòÉΓòÉ
  1307.  
  1308. This function drops a function from the macrospace. 
  1309.  
  1310. Syntax:
  1311.  
  1312.   droprc = RxDropMacro(funcname)
  1313.  
  1314. where
  1315.  
  1316.   funcname   = name of function in macrospace
  1317.  
  1318. Note:
  1319.  
  1320.   Returned value is return code from RexxDropMacro.
  1321.  
  1322.  
  1323. ΓòÉΓòÉΓòÉ 9.3. RxClearMacroSpace - Clear Entire MacroSpace ΓòÉΓòÉΓòÉ
  1324.  
  1325. This function clears all functions from the macro space.  Be careful when using 
  1326. this as it will affect all processes in the system. 
  1327.  
  1328. Syntax:
  1329.  
  1330.   clear_rc = RxClearMacroSpace()
  1331.  
  1332. Note:
  1333.  
  1334.   Returned value is return code from RexxClearMacroSpace.
  1335.  
  1336.  
  1337. ΓòÉΓòÉΓòÉ 9.4. RxSaveMacroSpace - Save Macro to File ΓòÉΓòÉΓòÉ
  1338.  
  1339. This function saves a macrospace function to a file. 
  1340.  
  1341. Syntax:
  1342.  
  1343.   saverc = RxSaveMacroSpace(funcname, macfile)
  1344.  
  1345. where
  1346.  
  1347.   funcname = name of function in macrospace
  1348.   macfile  = name of file in which to save macro
  1349.  
  1350. Note:
  1351.  
  1352.   Returned value is return code from RexxSaveMacroSpace.
  1353.  
  1354.  
  1355. ΓòÉΓòÉΓòÉ 9.5. RxLoadMacroSpace - Load a Macro from File ΓòÉΓòÉΓòÉ
  1356.  
  1357. This function loads a macrospace function from a file. 
  1358.  
  1359. Syntax:
  1360.  
  1361.   loadrc = RxLoadMacroSpace(funcname, macfile)
  1362.  
  1363. where
  1364.  
  1365.   funcname = name of function in macrospace
  1366.   macfile  = name of file in which to save macro
  1367.  
  1368. Note:
  1369.  
  1370.   Returned value is return code from RexxLoadMacroSpace.
  1371.  
  1372.  
  1373. ΓòÉΓòÉΓòÉ 9.6. RxQueryMacro - Query MacroSpace ΓòÉΓòÉΓòÉ
  1374.  
  1375. This function queries the existence/position of a macro in the macrospace. 
  1376.  
  1377. Syntax:
  1378.  
  1379.   qinfo = RxQueryMacro(funcname)
  1380.  
  1381. where
  1382.  
  1383.   funcname = name of function in macrospace
  1384.   qinfo    = blank-delimited tokens:
  1385.              1) return code from RexxQueryMacro
  1386.                 If #1 is zero, then:
  1387.                 2) Before/After/?
  1388.  
  1389. Note:
  1390.  
  1391.   If first token is not zero, no other information was returned.
  1392.  
  1393.  
  1394. ΓòÉΓòÉΓòÉ 9.7. RxReorderMacro - Reorder Macro Position ΓòÉΓòÉΓòÉ
  1395.  
  1396. This function reorders the position of a macro within the macrospace. 
  1397.  
  1398. Syntax:
  1399.  
  1400.   reorderrc = RxReorderMacro(funcname, position)
  1401.  
  1402. where
  1403.  
  1404.   funcname = name of function in macrospace
  1405.   position = relative position in macrospace (Before/After)
  1406.  
  1407. Note:
  1408.  
  1409.   Returned value is return code from RexxReorderMacro
  1410.  
  1411.  
  1412. ΓòÉΓòÉΓòÉ 10. Threads, Tasking, etc. ΓòÉΓòÉΓòÉ
  1413.  
  1414. These functions allow a Rexx program to start and control new threads and 
  1415. processes. 
  1416.  
  1417.  
  1418. ΓòÉΓòÉΓòÉ 10.1. RxExecPgm - Execute a program ΓòÉΓòÉΓòÉ
  1419.  
  1420. This function starts another program in the same session. 
  1421.  
  1422. Syntax:
  1423.  
  1424.   exrc = RxExecPgm(pgmname [, mode [,argstring]])
  1425.  
  1426. where
  1427.  
  1428.   pgmname   = name of .EXE file to execute
  1429.   mode      = 'S'ync, 'A'sync, async'R'esult, 'T'race, 'B'ackground, 'L'oad,
  1430.               asyncresult'D'b.
  1431.               Default is 'S'ync.
  1432.   argstring = arg string to pass to program
  1433.   exrc      = three blank-delimited tokens:
  1434.               1) return code from DosExecPgm
  1435.               2) termination code / process-id (for asynchronous)
  1436.               3) new program's return code
  1437.  
  1438.  
  1439. ΓòÉΓòÉΓòÉ 10.2. RxStartSession - Start Another Session ΓòÉΓòÉΓòÉ
  1440.  
  1441. This function starts a program in another OS/2 session. 
  1442.  
  1443. Syntax:
  1444.  
  1445.   strc = RxStartSession(pgmname [,args [,related [,fgbg [,title [,type
  1446.                         [,ctrl] ] ] ] ] ])
  1447.  
  1448. where
  1449.  
  1450.   pgmname   = name of .EXE file to execute
  1451.   args      = arg string to pass to program
  1452.   related   = Relation of started session to this session, can be:
  1453.               'I'ndependent or 'C'hild
  1454.   fgbg      = Foreground/Background option, can be:
  1455.               'F'oreground or 'B'ackground
  1456.   title     = Session title (defaults to program name)
  1457.   type      = Program type, can be:
  1458.               'D'efault, 'F'ullscreen, 'P'M, 'V'irtual-Dos,
  1459.               'W'indowed-Virtual-Dos, vi'O'-windowable
  1460.   ctrl      = Program control, can be:
  1461.               'V'isible, 'I'nvisible, ma'X'imized, mi'N'imized,
  1462.               no'A'utoclose
  1463.   strc      = if DosStartSession failed:
  1464.               - return code from DosStartSession followed by error info
  1465.               if DosStartSession got zero rc:
  1466.               - return code from DosStartSession Session-ID Process-ID
  1467.  
  1468.  
  1469. ΓòÉΓòÉΓòÉ 10.3. RxStartRexxSession - Start a Rexx program on another session ΓòÉΓòÉΓòÉ
  1470.  
  1471. This function starts a Rexx program in another OS/2 session. (The .EXE 
  1472. "rxsrs.exe" must be in your path in order to use this function) 
  1473.  
  1474. Syntax:
  1475.  
  1476.   strc = RxStartRexxSession(execname [,arg1] [,arg2] ... [,argn])
  1477.  
  1478. where
  1479.  
  1480.   execname = name of Rexx program to execute
  1481.                    or
  1482.              a '$' immediately preceding a source program string
  1483.                    or
  1484.              a '&' immediately preceding a tokenized program string
  1485.              (for more info about these, see "RxCallInStore" and
  1486.               "RxTokenize")
  1487.   arg1     = arguments 1-n for target Rexx program
  1488.   ...
  1489.   argn
  1490.   strc     = if DosStartSession failed:
  1491.              - return code from DosStartSession followed by error info
  1492.              if DosStartSession worked:
  1493.              - return code from DosStartSession Session-ID Process-ID
  1494.  
  1495.  
  1496. ΓòÉΓòÉΓòÉ 10.4. RxKillProcess - Kill an OS/2 Process ΓòÉΓòÉΓòÉ
  1497.  
  1498. This function kills an OS/2 process by process-id. 
  1499.  
  1500. Syntax:
  1501.  
  1502.   killrc = RxKillProcess(pid [, action])
  1503.  
  1504. where
  1505.  
  1506.   pid    = process-id (decimal integer)
  1507.   action = 'Process' or 'Tree' (default is 'Process')
  1508.   killrc = return code from DosKillProcess
  1509.  
  1510.  
  1511. ΓòÉΓòÉΓòÉ 10.5. RxCreateThread - Start new thread ΓòÉΓòÉΓòÉ
  1512.  
  1513. This function starts execution at a supplied entry point on a new thread. The 
  1514. entry point is any valid procedure address (e.g. obtained by a call to 
  1515. RxQueryProcAddr, etc.). 
  1516.  
  1517. Syntax:
  1518.  
  1519.   tid = RxCreateThread(procaddr [, dataptr [, linktype [, stacksize
  1520.                                 [, threadflag]]]])
  1521.  
  1522. where
  1523.  
  1524.   procaddr     = Procedure Address
  1525.   dataptr      = pointer to arguments
  1526.   linktype     = 'System' or 'Optlink'
  1527.                  If linktype is 'System', then args 4 and 5 are:
  1528.     stacksize  = stacksize for thread (default is 8192)
  1529.     threadflag = 'Immediate' or 'Suspend'
  1530.   tid          = thread-id of new thread
  1531.  
  1532. Note:
  1533.   Pointer to arguments is optional, but if supplied must be a valid pointer.
  1534.  
  1535.  
  1536. ΓòÉΓòÉΓòÉ 10.6. RxKillThread - Kill a thread ΓòÉΓòÉΓòÉ
  1537.  
  1538. This function kills a thread by thread-id. 
  1539.  
  1540. Syntax:
  1541.  
  1542.   killrc = RxKillThread(tid)
  1543.  
  1544. where
  1545.  
  1546.   tid    = thread-id
  1547.   killrc = return code from DosKillThread
  1548.  
  1549.  
  1550. ΓòÉΓòÉΓòÉ 10.7. RxSetPriority - Set the priority of processes or threads ΓòÉΓòÉΓòÉ
  1551.  
  1552. This function sets the priority of one or more process and/or threads. 
  1553.  
  1554. Syntax:
  1555.  
  1556.   setrc = RxSetPriority(scope,class,delta,id)
  1557.  
  1558. where
  1559.  
  1560.   scope = 'P'rocess (default)
  1561.           t'R'ee
  1562.           'T'hread
  1563.   class = 'N'ochange (default)
  1564.           'I'dletime
  1565.           'R'egular
  1566.           'T'imecritical
  1567.           foreground'S'erver
  1568.   delta = any integer from -31 to +31, or ma'X'imum, or mi'N'imum
  1569.   id    = a Process-Id, Thread-Id, or nothing, depending on value
  1570.           of "scope"
  1571.   setrc = return code from DosSetPriority
  1572.  
  1573.  
  1574. ΓòÉΓòÉΓòÉ 10.8. RxResumeThread - Resume thread execution ΓòÉΓòÉΓòÉ
  1575.  
  1576. This function causes a thread to resume execution 
  1577.  
  1578. Syntax:
  1579.  
  1580.   resrc = RxResumeThread(tid)
  1581.  
  1582. where
  1583.  
  1584.   tid   = thread-id
  1585.   resrc = return code from DosResumeThread
  1586.  
  1587.  
  1588. ΓòÉΓòÉΓòÉ 10.9. RxSuspendThread - Suspend thread execution ΓòÉΓòÉΓòÉ
  1589.  
  1590. This function causes a thread to suspend execution 
  1591.  
  1592. Syntax:
  1593.  
  1594.   susrc = RxSuspendThread(tid)
  1595.  
  1596. where
  1597.  
  1598.   tid   = thread-id
  1599.   susrc = return code from DosSuspendThread
  1600.  
  1601.  
  1602. ΓòÉΓòÉΓòÉ 10.10. RxCreateRexxThread - Rexx on another thread ΓòÉΓòÉΓòÉ
  1603.  
  1604. This function executes a Rexx program on another thread of the same process. 
  1605. The started Rexx program has a separate variable pool, and maintains its own 
  1606. "current Rexx queue", indpendently of the starting Rexx program.  But all other 
  1607. features of multi-threaded applications apply (i.e. shared file handles, etc.) 
  1608.  
  1609. Syntax:
  1610.  
  1611.   tid = RxCreateRexxThread(execname [,arg1 [,arg2 [, ...]]])
  1612.  
  1613. where
  1614.  
  1615.   execname = name of Rexx program to execute
  1616.                    or
  1617.              a '$' immediately preceding a source program string
  1618.                    or
  1619.              a '&' immediately preceding a tokenized program string
  1620.              (for more info about these, see "RxCallInStore" and
  1621.               "RxTokenize")
  1622.   arg1     = arguments to Rexx program (up to 19 possible)
  1623.   arg2
  1624.   ...
  1625.   tid      = Thread-Id of new thread
  1626.  
  1627. Note:
  1628.  
  1629.   Example of executing a program string:
  1630.  
  1631.     crlf = '0d0a'x
  1632.     str = '/* Rexx */'crlf
  1633.     str = str 'Do i=1 To Arg()'crlf
  1634.     str = str '  Say "Arg#"i "= {"arg(i)"}"'crlf
  1635.     str = str 'End'crlf
  1636.     str = str||'1a'x       /* EOF marker */
  1637.     call rxcreaterexxthread '$'str, date(), time()
  1638.  
  1639.  
  1640. ΓòÉΓòÉΓòÉ 11. NETBIOS information ΓòÉΓòÉΓòÉ
  1641.  
  1642. These functions allow a Rexx program to access certain NETBIOS information. 
  1643.  
  1644.  
  1645. ΓòÉΓòÉΓòÉ 11.1. RxNbSessionStatus - NetBios Session Status ΓòÉΓòÉΓòÉ
  1646.  
  1647. This function gets NetBios session status information. 
  1648.  
  1649. Syntax:
  1650.  
  1651.   nbname = 'S$SQLDBSERVR1#DB'
  1652.  
  1653.   nbrc =  RxNbSessionStatus(nbname,'s.','r')
  1654.  
  1655. Note:
  1656.  
  1657.   Return code is from NETBIOS api.  Second argument is name of a Rexx stem
  1658.   variable under which results are returned as such:
  1659.  
  1660.     stem.0 = number of sessions reported on
  1661.       stem.n.1 = Local session number
  1662.       stem.n.2 = Session state
  1663.       stem.n.3 = Local name
  1664.       stem.n.4 = Remote name
  1665.       stem.n.5 = Number of receive commands pending
  1666.       stem.n.6 = Number of send commands pending
  1667.  
  1668.   Third argument may be supplied to have a NETBIOS "Reset" done before and
  1669.   after obtaining session status.
  1670.  
  1671.  
  1672. ΓòÉΓòÉΓòÉ 12. DLL Handling ΓòÉΓòÉΓòÉ
  1673.  
  1674. These functions allow a Rexx program to load and execute procedures with- in 
  1675. DLL's.  Also, certain information about DLL's can be obtained. 
  1676.  
  1677.  
  1678. ΓòÉΓòÉΓòÉ 12.1. RxLoadModule - Load a DLL ΓòÉΓòÉΓòÉ
  1679.  
  1680. This function loads a DLL, returning a module handle (or an error code). 
  1681.  
  1682. Syntax:
  1683.  
  1684.   dosrc = RxLoadModule(rexxvar, dllname)
  1685.  
  1686. where:
  1687.  
  1688.   rexxvar = name of rexx variable in which module handle is returned
  1689.   dllname = name of DLL to load
  1690.   dosrc   = return code from DosLoadModule
  1691.  
  1692.  
  1693. ΓòÉΓòÉΓòÉ 12.2. RxFreeModule - Free a DLL ΓòÉΓòÉΓòÉ
  1694.  
  1695. This function frees the DLL whose module handle is supplied. 
  1696.  
  1697. Syntax:
  1698.  
  1699.   dosrc = RxFreeModule(hmod)
  1700.  
  1701. where:
  1702.  
  1703.   hmod    = module handle
  1704.   dosrc   = return code from DosFreeModule
  1705.  
  1706.  
  1707. ΓòÉΓòÉΓòÉ 12.3. RxQueryModuleName - Get Module Name ΓòÉΓòÉΓòÉ
  1708.  
  1709. This function returns the name of a module, given the module handle. 
  1710.  
  1711. Syntax:
  1712.  
  1713.   dosrc = RxQueryModuleName(rexxvar,hmod)
  1714.  
  1715. where:
  1716.  
  1717.   rexxvar = name of rexx variable in which module name is returned
  1718.   hmod    = module handle of DLL
  1719.   dosrc   = return code from DosQueryModuleName
  1720.  
  1721.  
  1722. ΓòÉΓòÉΓòÉ 12.4. RxQueryModuleHandle - Get Module Handle ΓòÉΓòÉΓòÉ
  1723.  
  1724. This function returns the handle of a module, given the module's name. 
  1725.  
  1726. Syntax:
  1727.  
  1728.   dosrc = RxQueryModuleHandle(rexxvar,modname)
  1729.  
  1730. where:
  1731.  
  1732.   rexxvar = name of rexx variable in which module handle is returned
  1733.   modname = name of DLL
  1734.   dosrc   = return code from DosQueryModuleHandle
  1735.  
  1736.  
  1737. ΓòÉΓòÉΓòÉ 12.5. RxQueryProcType - Query Procedure Type ΓòÉΓòÉΓòÉ
  1738.  
  1739. This function returns the addressing mode (16/32 bit) of a procedure of a DLL. 
  1740. The procedure can be identified either by name, or ordinal number. 
  1741.  
  1742. Syntax:
  1743.  
  1744.   entryname = 'SQLEXEC'
  1745.   ordinal = 3
  1746.  
  1747.   procinfo = RxQueryProcType(hmod,procid)
  1748.   amode = RxQueryProcType(hmod,entryname)
  1749.  
  1750. where:
  1751.  
  1752.   hmod     = module handle
  1753.   procid   = procedure-id (either an ordinal, or a procedure name)
  1754.   procinfo = Two blank-delimited tokens:
  1755.              1) return code from DosQueryProcType
  1756.              2) either "16" or "32", indicating 16 or 32 bit
  1757.  
  1758.  
  1759. ΓòÉΓòÉΓòÉ 12.6. RxQueryProcAddr - Query Procedure Address ΓòÉΓòÉΓòÉ
  1760.  
  1761. This function returns the address of an entry point in a DLL.  This entry point 
  1762. can then be used in RxCallEntryPoint to call an entry point in a Loaded DLL. 
  1763.  
  1764. Syntax:
  1765.  
  1766.   entryname = 'SQLEXEC' /* Entry name */
  1767.               3         /* Entry ordinal */
  1768.  
  1769.   dosrc = RxQueryProcAddr(rexxvar,hmod,procid)
  1770.  
  1771. where:
  1772.  
  1773.   rexxvar = name of rexx variable in which procedure address is returned
  1774.   hmod    = module handle of DLL
  1775.   procid  = procedure-id (either an ordinal, or a procedure name)
  1776.  
  1777.  
  1778. ΓòÉΓòÉΓòÉ 12.7. RxCallEntryPoint - Call an entry point ΓòÉΓòÉΓòÉ
  1779.  
  1780. This function "calls" the code which begins at the ProcAddress supplied. This 
  1781. ProcAddress could be the address obtained by RxQueryProcAddr for the entry 
  1782. point of a DLL.  But, it can be any "legal" entry point address of any routine. 
  1783.  
  1784. Syntax:
  1785.  
  1786.   procrc = RxCallEntryPoint(procaddr [,arg1 [, arg2 [,...]]] )
  1787.  
  1788. where
  1789.  
  1790.   procaddr = proc-address (could be obtained from RxQueryProcAddr, etc.)
  1791.   parg1
  1792.   ...
  1793.   parg19   = up to 19 arguments.  If an argument is a valid pointer, the
  1794.              pointer will be passed.  If not, a copy of the argument's value
  1795.              will be passed by reference.  Either way, the procedure must be
  1796.              expecting a pointer for each argument.
  1797.   procrc   = return code from the procedure
  1798.  
  1799. Note:
  1800.   Linkage to the proc-address is type _System.
  1801.  
  1802.  
  1803. ΓòÉΓòÉΓòÉ 13. OS/2 Pipes ΓòÉΓòÉΓòÉ
  1804.  
  1805. An assortment of OS/2 pipe-related functions (not complete). 
  1806.  
  1807.  
  1808. ΓòÉΓòÉΓòÉ 13.1. RxCreateNPipe - Create a named pipe ΓòÉΓòÉΓòÉ
  1809.  
  1810. This function creates an OS/2 named pipe. 
  1811.  
  1812. Syntax:
  1813.  
  1814.   dosrc = RxCreateNPipe( rexxvar, pipename, openmode, pipemode,
  1815.                          instance_count, outbufsize, inbufsize,
  1816.                          timeout)
  1817.  
  1818. where
  1819.  
  1820.    rexxvar  = name of Rexx variable into which read/write handle is placed
  1821.    pipename = name of pipe
  1822.  
  1823.    OpenMode Values
  1824.      W    = WriteBehind
  1825.      w    = NoWriteBehind
  1826.      I    = Inherit
  1827.      i    = NoInherit
  1828.      N(n) = Access Inbound
  1829.      O(o) = Access Outbound
  1830.      D(d) = Access Duplex
  1831.  
  1832.    PipeMode Values
  1833.      W    = Wait
  1834.      w    = NoWait
  1835.      T    = Pipe Type "Byte"
  1836.      t    = Pipe Type "Message"
  1837.      R    = Readmode "Byte"
  1838.      r    = Readmode "Message"
  1839.  
  1840.    Instance_Count
  1841.      Integer
  1842.  
  1843.    Outbuf Size
  1844.      Integer
  1845.  
  1846.    Inbuf Size
  1847.      Integer
  1848.  
  1849.    Timeout
  1850.      Integer
  1851.  
  1852.   dosrc   = return code from DosCreateNPipe()
  1853.  
  1854.  
  1855. ΓòÉΓòÉΓòÉ 13.2. RxConnectNPipe - Connect to a named pipe ΓòÉΓòÉΓòÉ
  1856.  
  1857. This function connects to a named pipe 
  1858.  
  1859. Syntax:
  1860.  
  1861.   dosrc = RxConnectNPipe(hpipe)
  1862.  
  1863. where
  1864.  
  1865.    hpipe  = pipe handle
  1866.    dosrc  = return code from DosConnectNPipe()
  1867.  
  1868.  
  1869. ΓòÉΓòÉΓòÉ 13.3. RxDisConnectNPipe - Disconnect from a named pipe ΓòÉΓòÉΓòÉ
  1870.  
  1871. This function disconnects from a named pipe 
  1872.  
  1873. Syntax:
  1874.  
  1875.   dosrc = RxDisConnectNPipe(hpipe)
  1876.  
  1877. where
  1878.  
  1879.    hpipe  = pipe handle
  1880.    dosrc  = return code from DosDisConnectNPipe()
  1881.  
  1882.  
  1883. ΓòÉΓòÉΓòÉ 13.4. RxCreatePipe - Create an un-named pipe ΓòÉΓòÉΓòÉ
  1884.  
  1885. This function creates an OS/2 un-named pipe 
  1886.  
  1887. Syntax:
  1888.  
  1889.   dosrc = RxCreatePipe(rexxstem [,pipesize])
  1890.  
  1891. where
  1892.  
  1893.    rexxstem = name of Rexx stem variable under which read handle,
  1894.               write handle, and pipe size are returned as such:
  1895.               stem.1 = read handle
  1896.               stem.2 = write handle
  1897.               stem.3 = pipe size
  1898.    dosrc  = return code from DosCreatePipe()
  1899.  
  1900.  
  1901. ΓòÉΓòÉΓòÉ 13.5. RxDestroyPipe - Destroy an un-named pipe ΓòÉΓòÉΓòÉ
  1902.  
  1903. This function destroys an OS/2 un-named pipe 
  1904.  
  1905. Syntax:
  1906.  
  1907.   dosrc = RxDestroyPipe(hread,hwrite)
  1908.  
  1909. where
  1910.  
  1911.    hread  = read handle
  1912.    hwrite = write handle
  1913.    dosrc  = return codes from DosClose()
  1914.  
  1915.  
  1916. ΓòÉΓòÉΓòÉ 14. I/O Related ΓòÉΓòÉΓòÉ
  1917.  
  1918. Miscellaneous functions related to I/O operations. 
  1919.  
  1920.  
  1921. ΓòÉΓòÉΓòÉ 14.1. RxRead - Read from File Handle ΓòÉΓòÉΓòÉ
  1922.  
  1923. This function reads a character stream in from a file handle, rather than from 
  1924. a file name. 
  1925.  
  1926. Syntax:
  1927.  
  1928.   dosrc = RxRead( rexxvar, hfile [,length] )
  1929.  
  1930. where
  1931.  
  1932.   rexxvar = name of Rexx variable into which read data is placed
  1933.   hfile   = handle of file to be read from
  1934.   length  = number of bytes to read (defaults to zero)
  1935.   dosrc   = two blank-delimited words:
  1936.             1) return code from DosRead
  1937.             2) if (1) is zero, an integer indicating number of bytes
  1938.                read (should be same as length of rexx variable's
  1939.                value)
  1940.  
  1941.  
  1942. ΓòÉΓòÉΓòÉ 14.2. RxWrite - Write to File Handle ΓòÉΓòÉΓòÉ
  1943.  
  1944. This function writes a character stream out to a file handle, rather than from 
  1945. a file name. 
  1946.  
  1947. Syntax:
  1948.  
  1949.   dosrc = RxWrite( hfile , data )
  1950.  
  1951. where
  1952.  
  1953.   hfile = handle of file to be written to
  1954.   data  = data to be written to file
  1955.   dosrc   = two blank-delimited words:
  1956.             1) return code from DosWrite
  1957.             2) if (1) is zero, an integer indicating number of bytes
  1958.                written (may not be same as length of data supplied)
  1959.  
  1960.  
  1961. ΓòÉΓòÉΓòÉ 14.3. RxCloseH - Close a File Handle ΓòÉΓòÉΓòÉ
  1962.  
  1963. This function closes a file handle. 
  1964.  
  1965. Syntax:
  1966.  
  1967.   closerc = RxCloseH(hfile)
  1968.  
  1969. where
  1970.  
  1971.   hfile   = handle of file to be closed
  1972.   closerc = return code from DosClose
  1973.  
  1974.  
  1975. ΓòÉΓòÉΓòÉ 14.4. RxExecI - Read data into a Rexx queue or stem from a file ΓòÉΓòÉΓòÉ
  1976.  
  1977. This function reads (text) data into a Rexx queue or stem variable from a file. 
  1978. It is meant to be like EXECIO in TSO and VM, and can be used in a similar 
  1979. fashion for file input. 
  1980.  
  1981. Syntax:
  1982.  
  1983.   info = RxExecI([fname], [qtype], [name], [type])
  1984.  
  1985. where:
  1986.  
  1987.   fname  = name of file to be written to (default sends to stdout)
  1988.   qtype  = 'Lifo' or 'Fifo' (default is 'Fifo')
  1989.            determines how lines are placed on queue
  1990.            (ignored for stems)
  1991.   name   = name of Rexx queue from which to put data (default uses
  1992.            current queue)
  1993.                or
  1994.            name of a Rexx stem variable under which data is mapped as
  1995.              stem.0 = number of lines (stem.1 - stem.n)
  1996.              stem.1
  1997.              stem.2
  1998.              ...
  1999.              stem.n
  2000.   type   = 'Queue' or 'Stem' (default is 'Queue')
  2001.            this tells whether arg 3 is a Rexx Queue name or a stem
  2002.            variable name
  2003.   info   = two blank delimited numbers:
  2004.            1) number of lines read
  2005.            2) total number of bytes read
  2006.  
  2007. Example:
  2008.  
  2009.   /* Read a text file into the Rexx stem 's.' */
  2010.   info = rxexeci('c:\config.sys',,'s.','s')
  2011.   parse var info lines bytes
  2012.   Say lines 'lines were read'
  2013.   Say bytes 'bytes were read'
  2014.  
  2015.  
  2016. ΓòÉΓòÉΓòÉ 14.5. RxExecO - Write data from a Rexx queue or stem to a file ΓòÉΓòÉΓòÉ
  2017.  
  2018. This function writes data from a Rexx queue or stem variable to a file.  It is 
  2019. meant to be like EXECIO in TSO and VM, and can be used in a similar fashion for 
  2020. file output. 
  2021.  
  2022. Syntax:
  2023.  
  2024.   info = RxExecO([fname], [action], [name], [type])
  2025.  
  2026. where:
  2027.  
  2028.   fname  = name of file to be written to (default sends to stdout)
  2029.   action = Replace or Append (default is 'Replace')
  2030.            replaces or appends to 'fname'
  2031.   name   = name of Rexx queue from which to get data (default uses
  2032.            current queue)
  2033.                or
  2034.            name of a Rexx stem variable under which data is mapped as
  2035.              stem.1
  2036.              stem.2
  2037.              ...
  2038.              stem.n
  2039.            Once an uninitialized value for 'stem.n' is encountered,
  2040.            i/o stops.
  2041.   type   = 'Queue' or 'Stem' (default is 'Queue')
  2042.            this tells whether arg 3 is a Rexx Queue name or a stem
  2043.            variable name
  2044.   info   = two blank delimited numbers:
  2045.            1) number of lines written
  2046.            2) total number of bytes written
  2047.  
  2048. Example:
  2049.  
  2050.   /* Write 100 lines from current queue to c:\junk.dat (replace file) */
  2051.   Do 100
  2052.     Queue i time('l')
  2053.   End
  2054.   info = rxexeco('c:\junk.dat','r')
  2055.   parse var info lines bytes
  2056.   Say lines 'lines were written'
  2057.   Say bytes 'bytes were written'
  2058.  
  2059.  
  2060. ΓòÉΓòÉΓòÉ 14.6. Rxrsoe2f - Redirect Std-Out/Err to File ΓòÉΓòÉΓòÉ
  2061.  
  2062. This function redirects Standard Out and Standard Error to a named file (or 
  2063. device name, such as "CON"). 
  2064.  
  2065. Syntax:
  2066.  
  2067.   opt = 'Append'
  2068.         'Replace'
  2069.  
  2070.   Call Rxrsoe2f 'sysout',opt
  2071.  
  2072.  
  2073. ΓòÉΓòÉΓòÉ 15. System-Info related ΓòÉΓòÉΓòÉ
  2074.  
  2075. Functions returning OS/2 system information. 
  2076.  
  2077.  
  2078. ΓòÉΓòÉΓòÉ 15.1. RxPstat - Get Process Status Information ΓòÉΓòÉΓòÉ
  2079.  
  2080. This function returns process status information (like PSTAT). 
  2081.  
  2082. Syntax:
  2083.  
  2084.   procrc = RxPStat(stemname)
  2085.  
  2086. where:
  2087.  
  2088.   stemname = a Rexx stem variable name under which results are
  2089.              mapped as such:
  2090.  
  2091.                stem.P.0 = number of processes
  2092.                stem.P.n.1 = process-id
  2093.                stem.P.n.2 = parent process-id
  2094.                stem.P.n.3 = process type
  2095.                stem.P.n.4 = process status
  2096.                stem.P.n.5 = process session-id
  2097.                stem.P.n.6 = process module name
  2098.                stem.P.n.T = process thread count
  2099.                stem.P.n.T.m.1 = thread-id within process
  2100.                stem.P.n.T.m.2 = unique thread slot number
  2101.                stem.P.n.T.m.3 = sleep-id thread is sleeping on
  2102.                stem.P.n.T.m.4 = thread priority
  2103.                stem.P.n.T.m.5 = thread state
  2104.                stem.P.n.T.m.6 = thread system time
  2105.                stem.P.n.T.m.7 = thread user time
  2106.   procrc   = return code from DosQProcStatus
  2107.  
  2108. Example:
  2109.  
  2110.   prc = rxpstat('s.')
  2111.   Say 'There are' s.p.0 'processes running right now'
  2112.  
  2113.  
  2114. ΓòÉΓòÉΓòÉ 15.2. RxProcId - Get process' own PID and TID information ΓòÉΓòÉΓòÉ
  2115.  
  2116. This function returns the process-id, parent process-id, and thread-id of the 
  2117. current thread of the current process. 
  2118.  
  2119. Syntax:
  2120.  
  2121.   procinfo = rxprocid()
  2122.  
  2123. where:
  2124.  
  2125.   procinfo = three blank delimited integers:
  2126.              1) process-id
  2127.              2) parent process-id
  2128.              3) thread-id
  2129.  
  2130.  
  2131. ΓòÉΓòÉΓòÉ 15.3. RxQuerySysInfo - Query OS/2 SysInfo ΓòÉΓòÉΓòÉ
  2132.  
  2133. This function returns live system information about OS/2 via the 
  2134. DosQuerySysInfo API. 
  2135.  
  2136. Syntax:
  2137.  
  2138.   rc = RxQuerySysInfo( stemname [,startidx [,endidx]])
  2139.  
  2140. where
  2141.  
  2142.   stemname = Rexx stem name, under which results are returned.  Each
  2143.              DosQuerySysInfo item is returned under the appropriate stem.n
  2144.              For instance, the call "call rxquerysysinfo('s.',3,5)" would
  2145.              set the rexx variables "s.3", "s.4", and "s.5".
  2146.   startidx = (see programming info for DosQuerySysInfo) Default is 1
  2147.   endidx   = (see programming info for DosQuerySysInfo) Default is 23
  2148.   rc       = return code from DosQuerySysInfo
  2149.  
  2150.  
  2151. ΓòÉΓòÉΓòÉ 16. PM / Wp related functions ΓòÉΓòÉΓòÉ
  2152.  
  2153. Functions related to PM or Workplace Shell Objects 
  2154.  
  2155.  
  2156. ΓòÉΓòÉΓòÉ 16.1. RxWinQueryObject - Query WP-Shell Object Handle ΓòÉΓòÉΓòÉ
  2157.  
  2158. This function returns the object handle of a WorkPlace Shell object. 
  2159.  
  2160. Syntax:
  2161.  
  2162.   hobj = RxWinQueryObject(objname)
  2163.  
  2164. where
  2165.  
  2166.   objname = name of WorkPlace Shell object
  2167.   hobj    = handle to object (or null string if not successful)
  2168.  
  2169.  
  2170. ΓòÉΓòÉΓòÉ 16.2. RxWinDestroyObject - Destroy a WP-Shell Object ΓòÉΓòÉΓòÉ
  2171.  
  2172. This function destroys a WorkPlace Shell object by object handle. 
  2173.  
  2174. Syntax:
  2175.  
  2176.   yorn = RxWinDestroyObject(hobj)
  2177.  
  2178. where
  2179.  
  2180.   hobj    = handle to object
  2181.   yorn    = "1" if it worked, "0" if it didn't
  2182.